TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)TA/(A)TAP.ADF/Documentation/keepDOC

Text File | 1988-10-23 | 12KB | 330 lines

                               G'day!








                            And welcome to...













c





                               Keep v1.2





     Copyright Notice: Keep v1.2 is
copyright (c) 1987, 1988 by Tim Grantham.
It may not be sold for profit, nor altered in any way, without
the permission of the author.

     Keep is an example of the latest in freely
distributable programs: Bonusware. That means that you
can copy this software as much as you want -- no donation is
required or requested (I won't send them back if I get them,
though. ;-) ) However, should you wish to have a copy of the
source code, send me $10 and a blank disk and I will happily
oblige. It's ugly code but it's only about the 15th program I've
ever written, in any language on any computer, and I'm damn
proud of it.

     I would appreciate any feedback users have about the
program. I can be reached at:

     55 Sorauren Ave.
     Toronto, Ontario
     Canada. M6R 2C9

     [phone]

     or on:

     PeopleLink: AMTAG
     BIX: dispatcher
     GEnie: t.grantham
     CIS: 71426,1646

     Keep those cards and letters coming, folks!


           What you are reading is the documentation for
version 1.2.  Those of you who simply wish to see what  has been
added to version 1.1 can jump to the end where the changes are
listed. I still recommend that you peruse the entire file:
some of the changes require a little explanation. The new
features are preceded by an asterisk (*).


     Keep is a utility program for BBS and network
junkies like myself who download messages in one large file and
then read them off-line. Using only the mouse, you can drive
through such files a message at a time, examine each at your
leisure and tag those you wish to keep. When the entire
file has been examined, keep goes through the file once
more and stores those messages that have been so tagged. The
original source file is left intact. *If a file with the same
name as the current output file is found, Keep will
give you the option of overwriting that file, appending to it
(useful when building a file from several source files) or
renaming the current output file. If no messages have been
tagged for saving, the source file will be closed and the program
will simply restart.

   Once running, Keep is (or should be)
self-explanatory. A possible source of ambiguity is the gadgets
at the top of the window. Selection of the arrows pointing up and
down permit the user to page through the text of each message.
The KEEP and DUMP
gadgets tag the message and advance to the next message. You can
select the left-pointing arrow to back up to the previous
message. Here you can change the fate of that message by
selecting the appropriate KEEP
or DUMP gadget. However, you must return to the
current message by selecting the right-pointing arrow before you
can move on to the next message in the file. *The `ghosted'
slider indicates how far into the file you've gone. I call it the
file gauge. :-)

  You can invoke Keep in a number of ways. If you are
using the Workbench, you can simply click on the icon
provided. If you are using the CLI, the recommended command is as
follows:

              run keep

Charlie Heath's excellent file requester is put up as soon as the
program starts so that you can pick the file to be examined. In
this case, the output file containing the kept messages
will be stored by default in the current directory.

However, you can specify the source file from the CLI thusly:

              run keep message_file

This will examine the file message_file and store the
messages to be kept in the file
message_file.kpt, in the current directory.

If you wish to cross directories, you can enter, for example

              run keep df1:message_file to
df0:file_name

The .kpt extension will be automatically
appended to the destination file name. You should specify
a destination file name. Simply entering, for example,

            run keep df1:message_file to df0:

will cause the kept file to appear simply as
.kpt on df0:.


     Keep opens its own screen to the same size as the
front-most screen. This is almost always the Workbench
screen. Thus, if you are using morerows or interlace to
get a larger display area, Keep will inherit it.

     Keep assumes that message files consist of lines
of no more than 120 characters, ending with a carriage return
(CR) and/or linefeed (LF). Any non-text character contained in
the line before the CR/LF will be displayed, usually as a
rectangle. CRs or LFs do not appear. They are, however, left
intact.


     You can at any time change the directory and name of the
destination file by selecting To... under the
Project menu.

    Skip terminates examination of the current file and
saves what messages had been tagged up to that point. *It then
saves all of the unread messages into another file in the same
directory with a .splt extension, e.g.
message_file.splt. (I'm afraid there is no option
to change the name of this file.) Skip is useful if its
3:00 am and you can't plow through another 250 messages before
you have to go to work in the morning. You can use Skip
to split the file into read and unread messages; later you can
pick up where you left off. You can even use the To...
option to append the kept messages to the original
.kpt file. A couple of caveats: the storing of the
unread messages is pretty slow in this version. Be patient.
Secondly, make sure there is enough room for the .splt file,
or the program will terminate!

     Abort terminates examination of the current file
completely and restarts the program.

     About provides some speculation as to the
inspiration for the Guru's meditations...

     *Tiny closes the Keep screen and puts up
a tiny window on the Workbench screen. This conserves
CHIP memory should you wish to switch to another program but
still leave Keep in memory. Keep also
provides support for users of the Tiny  Window Manager
created by Nick Sullivan of The Transactor for the
Amiga. If TWM is running, it will `gather up', so
to speak, Keep's tiny window into itself, along with
any other tiny windows created by other programs that can make
themselves clients of TWM.
     To bring the Keep screen back up, simply click the
mouse inside the tiny window. You will then find yourself exactly
where you were when you put up the tiny window. It's probably not
a good idea to select the Tiny option while the program
is storing the messages marked for saving.

     Quit exits the program.


     Keep does not have to be used exclusively for
information services. It can work with any text database that
uses a repeating header at the beginning of each record and
fields of no more than 120 characters delimited with CR and/or
LF. It looks for a search string of five characters or
less -- the shorter the string, the faster the search. You can
see which ones I have chosen: each time a network gadget is
selected in the service requester, the First line search
word string gadget is updated. You can click on this gadget
to customize the search string.

     *Special note to Usenet-ers: Because the headers on
Usenet/Pnet/Bitnet vary widely, the search string I have provided
may not be suitable. Use the string gadget to make the program
look for a string unique to your particular message header.


     If the program encounters a read error in the message file,
it will save those messages currently tagged and offer to restart
the program.

     If the program encounters an error during the writing of the
destination file, it will close that file and save to ram:
instead -- very handy if you just spent four hours going through
700+ messages. In this case, however, the default destination
file name will be used.


Enhancements to future versions of Keep may include:

     1. Much more attractive, Image-rendered
gadgets.

     2. Command line and menu support for interlace.

     3. More polished mutual exclude in the service
requester.

     4. Custom depth arrangement gadgets. The standard
ones are there, although only the top two rows of pixels are
visible. If you can grab those two rows, you can also slide the
screen down.

     5. Support for other BBSs and networks. Does
anybody know what. The Source uses for its message headers?

     6. Support for arbitrarily large files and
messages. *In this     version, Keep is confined to
files containing up to 4000 messages or records. In addition, it
reads in no more than 1000 lines at a time. This latter aspect
does not compromise the operation of the program should the
message be larger than 1000 lines. It simply splits it into
smaller pieces. If you want to save a complete message, save all
the pieces.

     7. More elegant command line parsing.

     8. The ability to use the mouse to mark
portions of messages for keeping.

     9. Word wrap for lines longer than 80 characters.

     10. Scrolling, rather than paging of text.

     Keep v2.0 will make use of the ARP
library, including the ARP file requester. It will also
most likely provide the ability to keep messages to
multiple files at once and the ability to use the Pipe: device
provided by some shell programs to permit a file to be
kept even as it is being downloaded.


     The shareware program blitzfonts works with
Keep and is highly recommended.


     I would like to thank Harvey Laser, Larry Pahlman and DARRYL
H for testing the various versions of this program. I especially
would like to thank the real Nick Sullivan, editor of
The Transactor for the Amiga for his endlessly patient
assistance. Keep is a direct descendant, several
generations removed, of a program Nick wrote in CBM Basic
and 6502 ML for the C64 and PET 8032.


     My greatest debt is to my wife Cate and my son Alex, for
their love.

Tim Grantham
April 26, 1988.


New features of Keep v1.2:

       1. A proportional gadget `file gauge' that shows you how
far into the source file you are.

       2. The Skip menu option now will save the
unexamined portion of the source file to a separate file, for
later perusal.

       3. Keep now checks to see if a destination file
already exists and if so, it provides an opportunity to append to
it, to overwrite it or to change the name of the current output.

       4. Keep is now runnable from the Workbench.
Check out the icon!

       5. If no messages have been marked for keeping,
no file will be opened -- Keep will simply restart.
Before, Keep created an empty file.

       6. Keep now can handle files containing up to
4000 messages. It will not recover nicely if this number
is exceeded but I find it hard to imagine a file of such a size.
You could always use the Skip option to gnaw on it a
piece at a time.

       7. Keep now has a tiny window option, and
supports Nick Sullivan's Tiny Window Manager . This
helps conserve CHIP memory.